home *** CD-ROM | disk | FTP | other *** search
/ NeXTSTEP 3.1 (Developer) [x86] / NeXT Step 3.1 Intel dev.cdr.dmg / NextDeveloper / Headers / bsd / dev / i386 / IOBufDevice.h < prev    next >
Encoding:
Text File  |  1993-04-30  |  15.7 KB  |  453 lines
  1. /*     Copyright (c) 1991 NeXT Computer, Inc.  All rights reserved. 
  2.  *
  3.  * IOBufDevice.h - Buffered Device abstract superclass. 
  4.  *
  5.  * HISTORY
  6.  * 13-Jan-93    John Seamons (jks) at NeXT
  7.  *    Ported to i386.
  8.  *
  9.  * 23-Jun-92    Mike DeMoney (mike@next.com)
  10.  *      Major hacks... 
  11.  *
  12.  * 16-Jul-91    Doug Mitchell at NeXT
  13.  *      Created.
  14.  */
  15.  
  16. #import <driverkit/i386/directDevice.h>
  17. #import    <mach/mach_types.h>
  18.  
  19. #define    MAX_OWNER_NAME_LEN    80
  20.  
  21. typedef    char *        DeviceStateName;
  22. typedef    unsigned    DeviceStateValue;
  23.  
  24. typedef    void *        Tag;
  25. typedef    char        OwnerName[MAX_OWNER_NAME_LEN+1];
  26.  
  27. /*
  28.  * BufferParameters -- information that characterizes data buffer
  29.  * requirements of the device.  User of the network device is expected
  30.  * to create buffers meeting these requirements.
  31.  *
  32.  * minAlignment        -- both the start address and end address
  33.  *               of the buffer must be aligned to this value.
  34.  *               MUST be a power of 2.  (NOTE: the buffer
  35.  *               end address alignment restriction does
  36.  *               not require the end of data itself to be
  37.  *               to be aligned, data may end at any point
  38.  *               within the buffer.)
  39.  *
  40.  * minBufferLength    -- the minimum buffer length that the driver
  41.  *               will accept.  (NOTE: this only limits the
  42.  *               actual buffer size, the data within the
  43.  *               buffer and the corresponding data length
  44.  *               specified in the transmitBuffer requests
  45.  *               may be of shorter length.)
  46.  *               
  47.  *
  48.  * privatePrefix    -- initial prefix of buffer that is for the
  49.  *               private use of the device driver.  The user
  50.  *               of the device driver should begin placing
  51.  *               data at this offset in the buffer.
  52.  *
  53.  * maxTransferUnit    -- the largest amount of data that the device
  54.  *               driver can accept as a "record" for transmission
  55.  *               or that the device driver will ever return
  56.  *               as a received "record".
  57.  *
  58.  * transmitFragmentOk    -- if TRUE, the device driver allows a single
  59.  *               transmit "record" to be fragmented across
  60.  *               multiple transmitData requests (the final
  61.  *               transmitData request must indicate "eor").
  62.  *               if FALSE, the entire transmit record must
  63.  *               be presented in a single transmitData request.
  64.  *
  65.  * receiveFragmentOk    -- if TRUE, the device driver can receive a
  66.  *               single received record into multiple
  67.  *               posted receive buffers of smaller length,
  68.  *               the final buffer will be marked "eor" by
  69.  *               the device driver.
  70.  *               if FALSE, the device driver will place
  71.  *               the received record into a single posted
  72.  *               receive buffer, the buffer will be marked
  73.  *               "eor".  Normally in this case, all receive
  74.  *               buffers should be large enough to receive a
  75.  *               "max Transfer Unit" record to avoid lost data.
  76.  *
  77.  * Buffer layout
  78.  *
  79.  *    bufferBaseAddress ->    +-------------------------------+
  80.  *    (must be aligned    | driver "private prefix data"    |
  81.  *    as per minAlignment)    |                 |
  82.  *                | (device driver will typically    |
  83.  *                | size this area to a multiple    |
  84.  *    bufferBaseAddress    | of minAlignment)        |
  85.  *    + privatePrefix ->    +-------------------------------+
  86.  *                | data area            |
  87.  *                | transmit data or receive data    |
  88.  *                | (devices not supporting    |
  89.  *                | fragments will typically    |
  90.  *                | require this to the data    |
  91.  *                | area to be at least        |
  92.  *                | maxTransferUnit bytes long)    |
  93.  *    bufferEndAddress ->    +-------------------------------+
  94.  *    (must be aligned
  95.  *    as per minAlignment,
  96.  *    must be greater than
  97.  *    or equal to
  98.  *    bufferBaseAddress
  99.  *    + minBufferLength)
  100.  */
  101.  
  102. /*
  103.  * Synchronous and asynchronous methods
  104.  *
  105.  * Methods in this interface are classified as either synchronous or
  106.  * asynchronous.  Synchronous methods complete there action before
  107.  * returning; asynchronous methods simply queue the request for action,
  108.  * this request may get processed after the method returns.  Actions
  109.  * requested by methods are always accomplished in the same order as the
  110.  * method invocations.
  111.  *
  112.  * Invoking any synchronous method forces all previously queued asynchronous
  113.  * methods to complete before processing the synchronous method.  This is
  114.  * useful to guarantee that when it is necessary to insure that an async
  115.  * method has completed.
  116.  */
  117.  
  118. typedef    struct    {
  119.     unsigned    minAlignment;
  120.     unsigned    minBufferLength;
  121.     unsigned    privatePrefix;
  122.     unsigned    maxTransferUnit;
  123.     BOOL        transmitFragmentOk;
  124.     BOOL        receiveFragmentOk;
  125. } BufferParameters;
  126.  
  127. /*
  128.  * IOBufDevice supports devices that have multiple "subunits" (e.g.
  129.  * DUART's).  Each subunit may be individually acquired.
  130.  */
  131. #define    MAX_IOBUFDEVICE_UNITS    4    // FIXME: Should be dynamic...
  132.  
  133. typedef struct {
  134.     id        callbackId;
  135.     Tag        deviceTag;
  136.     OwnerName    ownerName;
  137. } UnitInfo;
  138.  
  139. @interface IOBufDevice:IODirectDevice
  140. {
  141. @protected
  142.     UnitInfo unitInfo[MAX_IOBUFDEVICE_UNITS];
  143. }
  144.  
  145. /*
  146.  * Acquiring and releasing underlying device
  147.  *
  148.  * Subunits of an IOBufDevice are exclusive access.
  149.  *
  150.  * After successful acquire:
  151.  *    1. device will be disabled for receive, transmit and state changes.
  152.  *    2. no receive or transmit buffers will be queued
  153.  *    3. device will be initialized to a device-specific state
  154.  *
  155.  * When acquiring the device, the caller passes two pieces of information:
  156.  *    1. a callbackId, this is an id representing a caller provided
  157.  *       object.  This object will be messaged as per the
  158.  *       NetDeviceCallback protocol (defined below).
  159.  *    2. a deviceTag, this is opaque to the device driver, the device
  160.  *       simply passes the deviceTag on all future callbacks.
  161.  *
  162.  * If the device is not currently acquired by another device, the
  163.  * acquisition will succeed.  If the device is already acquired, the
  164.  * current owner will receive a callback indicating that the device
  165.  * is desired.  The current owner will then receive a callback indicating
  166.  * that ownership is being requested.  This callback will pass a character
  167.  * string indicating the "name" of the requester.  If the previous owner
  168.  * releases the device before returning from this callback, the new
  169.  * requestor will be granted the device.  Should the prevous owner not
  170.  * release the device, the new requestor will receive an error.
  171.  * NOTE: This is currently unimplemented.
  172.  *
  173.  * Buffers queued with the device at the time of a release request
  174.  * will be abandon by the device, the caller should issue flush
  175.  * requests before release if it requires the buffers to be returned.
  176.  */
  177. - (IOReturn)acquireUnit                : (unsigned) unitNumber
  178.                 for        : (OwnerName) ownerName
  179.                 callbackId    : (id) callbackId
  180.                 deviceTag    : (Tag) deviceTag;
  181. - (IOReturn)releaseUnit                : (unsigned) unitNumber;
  182. - (IOReturn)ownerForUnit            : (unsigned) unitNumber
  183.                 isNamed        : (OwnerName) ownerName;
  184.  
  185. /*
  186.  * Standard IODevice methods
  187.  */
  188. - (const char *)stringFromReturn        : (IOReturn) rtn;
  189. - (int)errnoFromReturn                 : (IOReturn) rtn;
  190. @end
  191.  
  192. /*
  193.  * Methods to be implemented by subclass.  These methods specify
  194.  * the common functionality of all IOBufDevice drivers.
  195.  */
  196. @protocol IOBufDeviceSubclass
  197.  
  198. /*
  199.  * Device initialization
  200.  *
  201.  * Device is initialized to device-specific state.
  202.  *
  203.  * initializeUnit may be called to re-initialize the device as necessary.
  204.  * NOTE: the device is forced to a device-specific state.  Any buffers
  205.  * queued are flushed.  Receive, transmit, and state changes are disabled.
  206.  * No state is watched.  The acquisition state of the device is not altered.
  207.  * After initializeUnit completes, the device should be totally quiescent:
  208.  * interrupts should be disabled and there should be no possibility of
  209.  * callbacks being generated.  InitializeUnit is invoked by the
  210.  * IOBufDevice superclass when processing an acquireUnit command.
  211.  *
  212.  * shutdownUnit puts the device into totally quiescent state.  It is
  213.  * invoked by the IOBufDevice superclass when processing a releaseUnit 
  214.  * command.  It is a programming error to use any method other than
  215.  * releaseUnit or initializeUnit immediately after having done a
  216.  * shutdownUnit.  releaseUnit performs a shutdownUnit.
  217.  *
  218.  * These methods are synchronous.
  219.  *
  220.  * FIXME: Get rid of shutdownUnit if at all possible, hopefully,
  221.  * initializeUnit will make the device quiescent.
  222.  */
  223. - (IOReturn)initializeUnit            : (unsigned) unitNumber;
  224.  
  225. - (IOReturn)shutdownUnit            : (unsigned) unitNumber;
  226.  
  227. /*
  228.  * Device enable and disable
  229.  *
  230.  * Devices may be enabled or disabled for:
  231.  *    1. transmit
  232.  *    2. receive
  233.  *    3. state changes (device-specific)
  234.  *
  235.  * Disabling a device prohibits the device from performing and/or reacting
  236.  * to function disabled.  Input and state changes are ignored while disabled.
  237.  * No callbacks will be generated after the disable action is complete
  238.  * (callbacks may occur during the processing of the disable).  Since
  239.  * setting of an enable is asynchronous, it may at times be necessary
  240.  * to follow the set of the enable by a synchronous method to guarantee
  241.  * that all callback have completed.
  242.  *
  243.  * Unless transmit (receive) buffers are flushed after disabling
  244.  * the transmitter (the receiver) the behavior of the device on
  245.  * re-enable is device specific.
  246.  *
  247.  * Enabling the receiver before having posted receive buffers may risk
  248.  * overruns for certain devices.  Likewise, enabling the transmitter before
  249.  * queuing transmit buffers may risk underrun.
  250.  *
  251.  * When state changes are enabled, immediate callbacks will be generated
  252.  * indicating the current state.  These callbacks pass a flag indicating
  253.  * that this is initial state, rather than a true state transition.
  254.  * Since setting the state change enable is asynchronous, it may be
  255.  * necessary to invoke a synchronous method to guarantee that
  256.  * all initial callbacks have completed.
  257.  *
  258.  * State change callbacks may be enabled and disabled with the method
  259.  * setStateEnable:; individual states may be added or deleted from
  260.  * the list of state variables tracked with setWatchEnable:enable:forUnit:.
  261.  *
  262.  * These methods are ASYNCHRONOUS.
  263.  */
  264. - (IOReturn)setRxEnable                : (BOOL) enableFlag
  265.                 forUnit        : (unsigned) unitNumber;
  266.  
  267. - (IOReturn)setTxEnable                : (BOOL) enableFlag
  268.                 forUnit        : (unsigned) unitNumber;
  269.  
  270. - (IOReturn)setStateEnable            : (BOOL) enableFlag
  271.                 forUnit        : (unsigned) unitNumber;
  272.  
  273. - (IOReturn)setWatchState            : (DeviceStateName) stateName
  274.                 enable        : (BOOL) newEnable
  275.                 forUnit        : (unsigned) unitNumber;
  276.  
  277. /*
  278.  * These methods are synchronous.
  279.  */
  280. - (BOOL)rxEnableForUnit                : (unsigned) unitNumber;
  281. - (BOOL)txEnableForUnit                : (unsigned) unitNumber;
  282. - (BOOL)stateEnableForUnit            : (unsigned) unitNumber;
  283. - (IOReturn)watchState                : (DeviceStateName) stateName
  284.                 enablePtr    : (BOOL *) enableP
  285.                 forUnit        : (unsigned) unitNumber;
  286.  
  287. /*
  288.  * Transmitting and receiving
  289.  *
  290.  * Transmit and receive buffers are "given" to the underlying device by
  291.  * these methods.  The device indicates completion or failure of the
  292.  * operation by a later appropriate callback.  The callback indicates a
  293.  * particular buffer by returning the bufferTag.
  294.  *
  295.  * Transmit buffers also may specify a buffer as the "end of record";
  296.  * interpretation of this flag is device-specific.
  297.  *
  298.  * The format of data within a transmit buffer is device specific.
  299.  * Certain devices may require that device specific headers be present
  300.  * in the data.  E.g. an Ethernet driver may require that the first bytes
  301.  * of data be the Ethernet source addr, dest addr, and type.
  302.  *
  303.  * Receive buffer addresses returned on callback may not be identical
  304.  * to the buffer address passed in with postReceiveBuffer (but the
  305.  * returned buffer will lie entirely within the original buffers
  306.  * range.  If the original buffer address is required by the caller,
  307.  * it should be determined via the bufferTag.
  308.  *
  309.  * NOTE: These methods may not fail.  The driver must always be prepared
  310.  * to queue transmit or receive buffers.
  311.  *
  312.  * In all cases, dataLength and maxDataLength refer ONLY to the data
  313.  * portion and do not include the privatePrefix.
  314.  *
  315.  * The vmTask parameter is either a task port (user space) or
  316.  * a vm_map_t (kernel space) and indicates the address space
  317.  * containing the buffer.
  318.  *
  319.  * These methods are ASYNCHRONOUS.
  320.  */
  321. - (IOReturn)transmitBuffer            : (void *) buffer
  322.                 dataLength    : (size_t) dataLength
  323.                 eor        : (BOOL) eor
  324.                 bufferTag    : (Tag) bufferTag
  325.                 vmTask        : (vm_task_t) vmTask
  326.                 forUnit        : (unsigned) unitNumber;
  327.  
  328. - (IOReturn)postReceiveBuffer            : (void *) buffer
  329.                 maxDataLength    : (size_t) maxDataLength
  330.                 bufferTag    : (Tag) bufferTag
  331.                 vmTask        : (vm_task_t) vmTask
  332.                 forUnit        : (unsigned) unitNumber;
  333.  
  334. /*
  335.  * Buffer management
  336.  *
  337.  * Buffers given to the underlying device may be forceably retrieved by
  338.  * the following flush methods -- pending actions are aborted (flushed
  339.  * transmit buffers may not have been transmitted, receive buffers may
  340.  * be empty).  Invoking a flush method will cause the underlying device
  341.  * to immediately return the buffers via callbacks.
  342.  *
  343.  * User of the underlying device should invoke the method bufferParameters
  344.  * and create buffers for transmission and reception that meet the
  345.  * requirements returned.
  346.  *
  347.  * These methods are asynchronous.
  348.  */
  349. - (IOReturn)flushTransmitBuffersForUnit        : (unsigned) unitNumber;
  350. - (IOReturn)flushReceiveBuffersForUnit        : (unsigned) unitNumber;
  351.  
  352. /*
  353.  * These methods are synchronous
  354.  */
  355. - (IOReturn)waitTransmitBuffersDoneForUnit    : (unsigned) unitNumber;
  356. - (BufferParameters)bufferParameters;
  357.  
  358. /*
  359.  * Device parameter management
  360.  *
  361.  * Inherits {get,set}Parameter{Int,Char} from IODevice class
  362.  *
  363.  * The set methods are asynchronous, the get methods synchronous.
  364.  */
  365.  
  366. /*
  367.  * "Commanded" control functions
  368.  *
  369.  * Commands are entirely device-specific.
  370.  */
  371. @end
  372.  
  373. @protocol IOBufDeviceCallback
  374. /*
  375.  * The methods described here are the callback methods that IOBufDevice
  376.  * subclass driver will invoke in the object registered as the callback
  377.  * object.
  378.  *
  379.  * These methods must be implemented by any client of a IOBufDevice.
  380.  *
  381.  * NOTE: It is illegal to invoke synchronous methods from a callback
  382.  * method.  Doing so will result in an error return.
  383.  *
  384.  * Since the client of this class must implement these methods, it
  385.  * doesn't make sense to characterize these methods as sync or async.
  386.  */
  387.  
  388. /*
  389.  * Buffer management.
  390.  *
  391.  * Transmit buffers are returned because the data was transmitted
  392.  * (with or without error) or the transmitter was flushed.  NOTE: Transmit
  393.  * buffers are guaranteed to be returned in the same order in which
  394.  * they were posted to the device.
  395.  *
  396.  * Similarly, receive buffers are returned either because data was
  397.  * received or the receiver was flushed.  The dataPtr returned may
  398.  * point to any location within the originally posted buffer
  399.  * (including within the privatePrefix!).
  400.  *
  401.  * Returned receive buffers may be marked by the device as "end of record",
  402.  * the meaning of this flag is device-specific.
  403.  *
  404.  * Format of the returned receive data is device-specific and may include
  405.  * media headers, etc.
  406.  */
  407. - (void)transmitDoneForUnit            : (unsigned) unitNumber
  408.                 bufferTag    : (Tag) bufferTag
  409.                 deviceTag    : (Tag) deviceTag
  410.                 bytesSent    : (size_t) bytesSent
  411.                 error        : (IOReturn) error;
  412.  
  413. - (void)receiveDoneForUnit            : (unsigned) unitNumber
  414.                 bufferTag    : (Tag) bufferTag
  415.                 deviceTag    : (Tag) deviceTag
  416.                 dataPtr        : (void *) dataPtr
  417.                 bytesReceived    : (size_t) bytesReceived
  418.                 eor        : (BOOL) eor
  419.                 error        : (IOReturn) error;
  420.  
  421. - (void)transmitError                : (IOReturn) error
  422.                 forUnit        : (unsigned) unitNumber
  423.                 deviceTag    : (Tag) deviceTag;
  424.  
  425. - (void)receiveError                : (IOReturn) error
  426.                 forUnit        : (unsigned) unitNumber
  427.                 deviceTag    : (Tag) deviceTag;
  428.  
  429. /*
  430.  * Watch'ed state change notification
  431.  *
  432.  * isInitial denotes that this callback indicates initial state as
  433.  * opposed to a state change.  "initial" callbacks are made
  434.  * whenever stateEnable transitions from FALSE to TRUE.
  435.  */
  436. - (void)watchChangeForUnit            : (unsigned) unitNumber
  437.                 watchState    : (DeviceStateName) stateName
  438.                 newValue    : (DeviceStateValue) stateValue
  439.                 initialChange    : (BOOL) isInitial
  440.                 deviceTag    : (Tag) deviceTag;
  441.  
  442. /*
  443.  * FIXME:  Define callback from ownership request.
  444.  */
  445. @end
  446.  
  447. /*
  448.  * IOReturn values specific to IOBufDevice
  449.  */
  450. #define    IO_R_FLUSHED    (-800)        /* buffer was flushed */
  451. #define    IO_R_NOT_OWNER    (-801)        /* not owner */
  452.  
  453.